Referencia Completa de Herramientas MCP.md•24 kB
# Referencia Completa de Herramientas MCP
Esta es la documentación completa de todas las herramientas MCP disponibles en el Servidor Selenium WebDriver.
## Índice
1. [Gestión de Navegadores](#gestión-de-navegadores)
2. [Navegación y Páginas](#navegación-y-páginas)
3. [Interacción con Elementos](#interacción-con-elementos)
4. [Acciones Avanzadas](#acciones-avanzadas)
5. [Evasión de Detección](#evasión-de-detección)
6. [Gestión de Sesiones](#gestión-de-sesiones)
7. [Gestión de Cookies](#gestión-de-cookies)
8. [Configuración del Servidor](#configuración-del-servidor)
---
## Gestión de Navegadores
### `start_browser`
Inicia una nueva sesión de navegador con configuraciones personalizables.
**Parámetros:**
- `browser_type` (str, opcional): Tipo de navegador ("chrome" o "firefox"). Por defecto: "chrome"
- `options` (dict, opcional): Opciones del navegador
- `proxy` (dict, opcional): Configuración de proxy
- `detection_evasion` (dict, opcional): Configuraciones para evasión de detección
**Opciones del navegador (`options`):**
```json
{
"headless": false,
"window_width": 1920,
"window_height": 1080,
"user_agent": "Mozilla/5.0...",
"disable_images": false,
"disable_javascript": false,
"incognito": true,
"custom_args": ["--no-sandbox", "--disable-dev-shm-usage"]
}
```
**Configuración de proxy (`proxy`):**
```json
{
"http": "http://proxy.example.com:8080",
"https": "https://proxy.example.com:8080",
"socks": "socks5://proxy.example.com:1080"
}
```
**Configuración de evasión (`detection_evasion`):**
```json
{
"use_undetected_chrome": true,
"stealth_mode": true,
"randomize_user_agent": true,
"randomize_viewport": true,
"disable_blink_features": true
}
```
**Respuesta:**
```json
{
"success": true,
"session_id": "abc123-def456",
"browser_type": "chrome",
"message": "Navegador chrome iniciado exitosamente"
}
```
**Ejemplo:**
```python
result = start_browser(
browser_type="chrome",
options={
"headless": True,
"window_width": 1280,
"window_height": 720,
"incognito": True
},
detection_evasion={
"use_undetected_chrome": True,
"stealth_mode": True
}
)
session_id = result["session_id"]
```
### `close_browser`
Cierra una sesión de navegador específica.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador a cerrar
**Respuesta:**
```json
{
"success": true,
"message": "Navegador cerrado exitosamente"
}
```
### `detect_available_browsers`
Detecta todos los navegadores disponibles en el sistema.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"success": true,
"browsers": {
"chrome": {
"name": "chrome",
"available": true,
"path": "/usr/bin/google-chrome",
"version": "Google Chrome 120.0.6099.109",
"supported_by_selenium": true
},
"firefox": {
"name": "firefox",
"available": true,
"path": "/usr/bin/firefox",
"version": "Mozilla Firefox 121.0",
"supported_by_selenium": true
}
},
"system_info": {
"system": "Linux",
"release": "5.4.0",
"architecture": "64bit"
},
"message": "Detectados 2 navegadores disponibles"
}
```
### `get_recommended_browser`
Obtiene el navegador recomendado basado en disponibilidad.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"success": true,
"recommended_browser": "chrome",
"webdriver_support": {
"selenium_support": true,
"webdriver_manager_support": true,
"undetected_chrome_support": true
},
"message": "Navegador recomendado: chrome"
}
```
### `check_browser_support`
Verifica el soporte de WebDriver para un navegador específico.
**Parámetros:**
- `browser_name` (str): Nombre del navegador a verificar
**Respuesta:**
```json
{
"success": true,
"browser": "chrome",
"support": {
"selenium_support": true,
"webdriver_manager_support": true,
"undetected_chrome_support": true
},
"message": "Información de soporte para chrome"
}
```
---
## Navegación y Páginas
### `navigate_to_url`
Navega a una URL específica.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `url` (str): URL a la que navegar
**Respuesta:**
```json
{
"success": true,
"current_url": "https://example.com/",
"title": "Example Domain",
"message": "Navegado exitosamente a https://example.com"
}
```
**Ejemplo:**
```python
result = navigate_to_url(session_id, "https://httpbin.org/forms/post")
print(f"Título: {result['title']}")
```
### `get_page_info`
Obtiene información de la página actual.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
**Respuesta:**
```json
{
"success": true,
"url": "https://example.com/",
"title": "Example Domain",
"page_source_length": 1256,
"window_size": {"width": 1920, "height": 1080},
"cookies_count": 3,
"message": "Información de página obtenida exitosamente"
}
```
### `execute_script`
Ejecuta JavaScript en el navegador.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `script` (str): Código JavaScript a ejecutar
- `*args`: Argumentos adicionales para el script
**Respuesta:**
```json
{
"success": true,
"result": {"title": "Example", "elements": 5},
"message": "Script ejecutado exitosamente"
}
```
**Ejemplo:**
```python
result = execute_script(
session_id,
"""
return {
title: document.title,
url: window.location.href,
elementCount: document.querySelectorAll('*').length
};
"""
)
print(f"Elementos en la página: {result['result']['elementCount']}")
```
---
## Interacción con Elementos
### `find_element`
Encuentra uno o múltiples elementos usando la estrategia especificada.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `strategy` (str): Estrategia de localización
- `value` (str): Valor del localizador
- `timeout` (int, opcional): Tiempo de espera en segundos. Por defecto: 10
- `multiple` (bool, opcional): Si buscar múltiples elementos. Por defecto: false
**Estrategias disponibles:**
- `id`: Por atributo ID
- `name`: Por atributo name
- `class_name`: Por clase CSS
- `tag_name`: Por nombre de etiqueta
- `css_selector`: Selector CSS
- `xpath`: Expresión XPath
- `link_text`: Texto exacto del enlace
- `partial_link_text`: Texto parcial del enlace
**Respuesta (elemento único):**
```json
{
"success": true,
"element": {
"tag_name": "input",
"text": "",
"is_displayed": true,
"is_enabled": true,
"location": {"x": 100, "y": 200},
"size": {"width": 200, "height": 30},
"attributes": {
"id": "search-input",
"name": "search",
"type": "text"
}
},
"message": "Elemento encontrado exitosamente"
}
```
**Respuesta (múltiples elementos):**
```json
{
"success": true,
"elements_found": 3,
"elements": [
{
"index": 0,
"tag_name": "button",
"text": "Submit",
"is_displayed": true,
"is_enabled": true,
"location": {"x": 150, "y": 300},
"size": {"width": 80, "height": 35},
"attributes": {"type": "submit", "class": "btn-primary"}
}
],
"message": "Encontrados 3 elementos"
}
```
**Ejemplos:**
```python
# Buscar por ID
element = find_element(session_id, "id", "submit-button")
# Buscar por CSS selector
element = find_element(session_id, "css_selector", ".form-control")
# Buscar múltiples elementos
elements = find_element(session_id, "css_selector", ".product-item", multiple=True)
# XPath complejo
element = find_element(session_id, "xpath", "//div[@class='content']//p[contains(text(), 'importante')]")
```
### `click_element`
Hace clic en un elemento.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `strategy` (str): Estrategia de localización
- `value` (str): Valor del localizador
- `timeout` (int, opcional): Tiempo de espera en segundos. Por defecto: 10
- `element_index` (int, opcional): Índice del elemento si hay múltiples coincidencias. Por defecto: 0
**Respuesta:**
```json
{
"success": true,
"message": "Elemento clickeado exitosamente"
}
```
**Ejemplo:**
```python
# Clic en botón por ID
click_element(session_id, "id", "submit-btn")
# Clic en segundo elemento de una lista
click_element(session_id, "css_selector", ".menu-item", element_index=1)
```
### `type_text`
Escribe texto en un elemento.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `strategy` (str): Estrategia de localización
- `value` (str): Valor del localizador
- `text` (str): Texto a escribir
- `timeout` (int, opcional): Tiempo de espera en segundos. Por defecto: 10
- `element_index` (int, opcional): Índice del elemento. Por defecto: 0
- `clear_first` (bool, opcional): Si limpiar el campo antes de escribir. Por defecto: true
**Respuesta:**
```json
{
"success": true,
"text_typed": "usuario@ejemplo.com",
"message": "Texto escrito exitosamente"
}
```
**Ejemplo:**
```python
# Escribir en campo de email
type_text(session_id, "id", "email", "usuario@ejemplo.com")
# Agregar texto sin limpiar
type_text(session_id, "id", "comments", " - Comentario adicional", clear_first=False)
```
### `upload_file`
Sube un archivo a un elemento input[type=file].
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `strategy` (str): Estrategia de localización del input file
- `value` (str): Valor del localizador
- `file_path` (str): Ruta del archivo a subir
- `timeout` (int, opcional): Tiempo de espera en segundos. Por defecto: 10
- `element_index` (int, opcional): Índice del elemento. Por defecto: 0
**Respuesta:**
```json
{
"success": true,
"file_path": "/path/to/document.pdf",
"message": "Archivo subido exitosamente"
}
```
**Ejemplo:**
```python
upload_file(
session_id,
"id",
"file-upload",
"/home/user/documents/resume.pdf"
)
```
---
## Acciones Avanzadas
### `perform_mouse_action`
Realiza acciones de ratón (hover, drag and drop, etc.).
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `action_type` (str): Tipo de acción
- `strategy` (str, opcional): Estrategia de localización del elemento origen
- `value` (str, opcional): Valor del localizador del elemento origen
- `element_index` (int, opcional): Índice del elemento origen. Por defecto: 0
- `x_offset` (int, opcional): Offset X para movimientos relativos. Por defecto: 0
- `y_offset` (int, opcional): Offset Y para movimientos relativos. Por defecto: 0
- `target_strategy` (str, opcional): Estrategia del elemento destino (para drag_and_drop)
- `target_value` (str, opcional): Valor del localizador del elemento destino
- `target_index` (int, opcional): Índice del elemento destino. Por defecto: 0
**Tipos de acción disponibles:**
- `hover`: Mover el ratón sobre un elemento
- `drag_and_drop`: Arrastrar y soltar entre elementos
- `right_click`: Clic derecho
- `double_click`: Doble clic
**Respuesta:**
```json
{
"success": true,
"action_type": "hover",
"message": "Acción hover realizada exitosamente"
}
```
**Ejemplos:**
```python
# Hover sobre elemento
perform_mouse_action(session_id, "hover", "id", "menu-item")
# Drag and drop
perform_mouse_action(
session_id,
"drag_and_drop",
strategy="id",
value="draggable-item",
target_strategy="id",
target_value="drop-zone"
)
# Clic derecho
perform_mouse_action(session_id, "right_click", "css_selector", ".context-menu-trigger")
# Doble clic
perform_mouse_action(session_id, "double_click", "id", "editable-text")
```
### `send_keys`
Envía teclas especiales (Enter, Tab, etc.) al navegador o a un elemento específico.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `keys` (str): Teclas a enviar
- `strategy` (str, opcional): Estrategia de localización del elemento
- `value` (str, opcional): Valor del localizador del elemento
- `element_index` (int, opcional): Índice del elemento. Por defecto: 0
**Teclas especiales disponibles:**
- `ENTER`, `TAB`, `ESCAPE`, `SPACE`
- `BACKSPACE`, `DELETE`
- `ARROW_UP`, `ARROW_DOWN`, `ARROW_LEFT`, `ARROW_RIGHT`
- `HOME`, `END`, `PAGE_UP`, `PAGE_DOWN`
- `F1` a `F12`
- `CONTROL`, `ALT`, `SHIFT`
**Respuesta:**
```json
{
"success": true,
"keys_sent": "ENTER",
"message": "Teclas 'ENTER' enviadas exitosamente"
}
```
**Ejemplos:**
```python
# Enviar Enter al elemento activo
send_keys(session_id, "ENTER")
# Enviar Tab a un elemento específico
send_keys(session_id, "TAB", "id", "input-field")
# Enviar combinación de teclas
send_keys(session_id, "CONTROL+A") # Seleccionar todo
```
### `take_screenshot`
Toma una captura de pantalla.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `file_path` (str, opcional): Ruta donde guardar la imagen
- `element_strategy` (str, opcional): Estrategia para capturar solo un elemento específico
- `element_value` (str, opcional): Valor del localizador del elemento
- `element_index` (int, opcional): Índice del elemento. Por defecto: 0
**Respuesta (guardando archivo):**
```json
{
"success": true,
"file_path": "/tmp/screenshot.png",
"message": "Captura guardada en /tmp/screenshot.png"
}
```
**Respuesta (datos base64):**
```json
{
"success": true,
"screenshot_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"message": "Captura tomada exitosamente"
}
```
**Ejemplos:**
```python
# Captura de pantalla completa
take_screenshot(session_id, "/tmp/full_page.png")
# Captura de un elemento específico
take_screenshot(
session_id,
"/tmp/element.png",
element_strategy="id",
element_value="main-content"
)
# Obtener datos base64 (sin guardar archivo)
result = take_screenshot(session_id)
base64_data = result["screenshot_base64"]
```
---
## Evasión de Detección
### `apply_stealth_mode`
Aplica todas las técnicas de evasión de detección a una sesión.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
**Respuesta:**
```json
{
"success": true,
"applied_scripts": [
"webdriver_property",
"chrome_runtime",
"permissions",
"plugins",
"languages"
],
"message": "Modo stealth aplicado exitosamente"
}
```
### `randomize_user_agent`
Cambia el user agent a uno aleatorio.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
**Respuesta:**
```json
{
"success": true,
"new_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
"message": "User agent randomizado exitosamente"
}
```
### `randomize_viewport`
Cambia el tamaño de la ventana a una resolución aleatoria.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
**Respuesta:**
```json
{
"success": true,
"new_size": {"width": 1366, "height": 768},
"message": "Viewport randomizado exitosamente"
}
```
### `simulate_human_typing`
Simula escritura humana con delays aleatorios entre teclas.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `strategy` (str): Estrategia de localización del elemento
- `value` (str): Valor del localizador
- `text` (str): Texto a escribir
- `min_delay` (float, opcional): Delay mínimo entre teclas. Por defecto: 0.05
- `max_delay` (float, opcional): Delay máximo entre teclas. Por defecto: 0.15
- `element_index` (int, opcional): Índice del elemento. Por defecto: 0
**Respuesta:**
```json
{
"success": true,
"text_typed": "búsqueda automatizada",
"characters": 19,
"message": "Texto escrito con simulación humana"
}
```
### `scroll_like_human`
Simula scroll humano con movimientos graduales.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `direction` (str, opcional): Dirección del scroll ("up" o "down"). Por defecto: "down"
- `distance` (int, opcional): Distancia total a scrollear en píxeles. Por defecto: 300
- `steps` (int, opcional): Número de pasos para dividir el movimiento. Por defecto: 5
**Respuesta:**
```json
{
"success": true,
"direction": "down",
"total_distance": 500,
"steps": 8,
"message": "Scroll down simulado exitosamente"
}
```
### `add_random_delay`
Agrega un delay aleatorio entre acciones.
**Parámetros:**
- `min_seconds` (float, opcional): Tiempo mínimo de delay. Por defecto: 0.5
- `max_seconds` (float, opcional): Tiempo máximo de delay. Por defecto: 2.0
**Respuesta:**
```json
{
"success": true,
"delay_seconds": 1.23,
"message": "Delay de 1.23 segundos aplicado"
}
```
---
## Gestión de Sesiones
### `list_active_sessions`
Lista todas las sesiones activas con información detallada.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"success": true,
"sessions": {
"abc123-def456": {
"browser_type": "chrome",
"created_at": 1703123456.789,
"last_activity": 1703123500.123,
"age_seconds": 43.334,
"current_url": "https://example.com",
"title": "Example Domain"
}
},
"total_sessions": 1,
"max_sessions": 10,
"message": "Listadas 1 sesiones activas"
}
```
### `get_session_info`
Obtiene información detallada de una sesión específica.
**Parámetros:**
- `session_id` (str): ID de la sesión
**Respuesta:**
```json
{
"success": true,
"session": {
"session_id": "abc123-def456",
"browser_type": "chrome",
"created_at": 1703123456.789,
"last_activity": 1703123500.123,
"age_seconds": 43.334,
"browser_info": {
"current_url": "https://example.com",
"title": "Example Domain",
"window_size": {"width": 1920, "height": 1080},
"cookies_count": 3,
"page_source_length": 1256
}
},
"message": "Información de sesión abc123-def456"
}
```
### `close_all_sessions`
Cierra todas las sesiones activas.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"success": true,
"sessions_closed": 3,
"message": "Cerradas 3 sesiones"
}
```
### `cleanup_expired_sessions`
Limpia las sesiones expiradas manualmente.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"success": true,
"sessions_before": 5,
"sessions_after": 3,
"sessions_cleaned": 2
}
```
---
## Gestión de Cookies
### `manage_cookies`
Gestiona cookies de la sesión.
**Parámetros:**
- `session_id` (str): ID de la sesión del navegador
- `action` (str): Acción a realizar
- `cookie_data` (dict, opcional): Datos de la cookie para agregar
- `cookie_name` (str, opcional): Nombre de la cookie para operaciones específicas
**Acciones disponibles:**
- `get_all`: Obtener todas las cookies
- `add`: Agregar una nueva cookie
- `delete`: Eliminar cookie(s)
- `get`: Obtener una cookie específica
**Estructura de cookie_data:**
```json
{
"name": "session_token",
"value": "abc123def456",
"domain": "example.com",
"path": "/",
"secure": true,
"httpOnly": false
}
```
**Respuesta (get_all):**
```json
{
"success": true,
"cookies": [
{
"name": "session_id",
"value": "abc123",
"domain": "example.com",
"path": "/",
"secure": false,
"httpOnly": true
}
],
"count": 1,
"message": "Obtenidas 1 cookies"
}
```
**Respuesta (add):**
```json
{
"success": true,
"message": "Cookie 'session_token' agregada"
}
```
**Respuesta (delete):**
```json
{
"success": true,
"message": "Cookie 'session_token' eliminada"
}
```
**Ejemplos:**
```python
# Obtener todas las cookies
cookies = manage_cookies(session_id, "get_all")
# Agregar una cookie
manage_cookies(
session_id,
"add",
cookie_data={
"name": "user_pref",
"value": "dark_mode",
"domain": "example.com"
}
)
# Obtener una cookie específica
cookie = manage_cookies(session_id, "get", cookie_name="session_id")
# Eliminar una cookie
manage_cookies(session_id, "delete", cookie_name="temp_token")
# Eliminar todas las cookies
manage_cookies(session_id, "delete")
```
---
## Configuración del Servidor
### `get_server_status`
Obtiene el estado actual del servidor.
**Parámetros:** Ninguno
**Respuesta:**
```json
{
"status": "running",
"active_sessions": 2,
"max_sessions": 10,
"default_browser": "chrome",
"session_timeout": 3600
}
```
### `update_server_config`
Actualiza la configuración del servidor con un preset predefinido.
**Parámetros:**
- `config_preset` (str, opcional): Preset de configuración. Por defecto: "default"
**Presets disponibles:**
- `default`: Configuración estándar
- `stealth`: Configuración optimizada para evasión de detección
- `performance`: Configuración optimizada para rendimiento
**Respuesta:**
```json
{
"success": true,
"new_config": "stealth",
"message": "Configuración actualizada. Todas las sesiones anteriores fueron cerradas."
}
```
---
## Recursos MCP
### `config://server`
Obtiene la configuración actual del servidor en formato JSON.
**Ejemplo de contenido:**
```json
{
"max_sessions": 10,
"session_timeout": 3600,
"default_browser": "chrome",
"browser_options": {
"headless": false,
"window_width": 1920,
"window_height": 1080,
"incognito": true
},
"detection_evasion": {
"use_undetected_chrome": true,
"stealth_mode": true,
"randomize_user_agent": true
}
}
```
### `sessions://active`
Lista todas las sesiones activas en formato JSON.
**Ejemplo de contenido:**
```json
{
"abc123-def456": {
"browser_type": "chrome",
"created_at": 1703123456.789,
"last_activity": 1703123500.123,
"age_seconds": 43.334
}
}
```
---
## Códigos de Error Comunes
| Código | Descripción | Solución |
|--------|-------------|----------|
| `Sesión no encontrada` | ID de sesión inválido o expirado | Verificar que la sesión esté activa |
| `Timeout: Elemento no encontrado` | Elemento no existe o no es visible | Revisar selector y aumentar timeout |
| `Estrategia no válida` | Estrategia de localización incorrecta | Usar una estrategia válida |
| `WebDriverException` | Error del driver de navegador | Reinstalar webdriver-manager |
| `ElementNotInteractableException` | Elemento no es interactuable | Hacer scroll o esperar visibilidad |
| `Archivo no encontrado` | Ruta de archivo inválida | Verificar que el archivo existe |
---
## Mejores Prácticas
### Manejo de Errores
Siempre verificar el campo `success` en las respuestas:
```python
result = click_element(session_id, "id", "submit-btn")
if result["success"]:
print("Clic exitoso")
else:
print(f"Error: {result['error']}")
```
### Timeouts Apropiados
Ajustar timeouts según la velocidad del sitio:
```python
# Para sitios lentos
find_element(session_id, "id", "slow-element", timeout=30)
# Para elementos que aparecen rápido
find_element(session_id, "id", "fast-element", timeout=5)
```
### Gestión de Sesiones
Cerrar sesiones cuando no se necesiten:
```python
# Al final del script
close_browser(session_id)
# O limpiar todas las sesiones
close_all_sessions()
```
### Evasión de Detección
Para sitios que detectan bots:
```python
# Configuración stealth completa
session_id = start_browser(
"chrome",
detection_evasion={"use_undetected_chrome": True, "stealth_mode": True}
)["session_id"]
apply_stealth_mode(session_id)
randomize_user_agent(session_id)
randomize_viewport(session_id)
# Usar delays y simulación humana
add_random_delay(1.0, 3.0)
simulate_human_typing(session_id, "id", "search", "query")
scroll_like_human(session_id, "down", 500, 8)
```